Apply expected consumption for all limits in one write - #60

The problem

An evaluation that touches two usage limits records one of them.

_applyExpectedConsumption reads the whole contract, increments a single usage
level in its own copy, and writes the whole contract back:

let contract = await this.cacheService.get(`contracts.${userId}`);
if (!contract) contract = await this.contractRepository.findByUserId(userId);
…
contract.usageLevels[serviceName][usageLimit].consumed += expectedConsumption;
const updatedContract = await this.contractRepository.update(userId, contract);

and evaluateFeature called it once per limit, concurrently:

const limits = Object.keys(featureEvaluation.used);
await Promise.all(
  limits.map(limit =>
    contractService._applyExpectedConsumption(options.userId!, limit, expectedConsumption[limit])
  )
);

Every call reads the same starting state, and each writes back its own copy of
the whole document. The last write wins and the other increments are gone.

Why it matters

This is on the path that decides whether somebody may use a feature, and it
fails silently: the evaluation returns true, the response looks right, and the
usage level for every limit but one is simply not moved. Nothing errors, so the
first sign is a quota that never seems to run out.

For a feature with a single usage limit — which is most of them — it never
happens, which is why it can sit unnoticed.

The change

_applyExpectedConsumptions(userId, Record<limitId, amount>) applies every
limit to one contract copy and writes once. Correct, and one round trip instead
of one per limit.

Every limit is validated before anything is written, so a request naming one
limit that does not exist cannot leave the others half-applied — the previous
code could apply some and then throw.

_applyExpectedConsumption stays, delegating, so nothing that calls it breaks.

The root fix, as requested

The first version of this PR batched the limits into one read and one write,
which stopped an evaluation from losing its own limits but left two requests
losing each other's. I flagged that here and @Alex-GF asked for the $inc
version, which is what this now is.

ContractRepository.incrementUsageLevels hands the arithmetic to the database:

const filter: Record<string, unknown> = { 'userContact.userId': userId };
const inc: Record<string, number> = {};

for (const [path, amount] of Object.entries(increments)) {
  filter[`usageLevels.${path}.consumed`] = { $exists: true };
  inc[`usageLevels.${path}.consumed`] = amount;
}

const contract = await ContractMongoose.findOneAndUpdate(filter, { $inc: inc }, { new: true });

Two things worth pointing out:

• $exists in the filter, not a prior read. Validation and the write are one
  operation, so a limit cannot be checked and then vanish before the update — and
  a limit that is not on the contract matches no document instead of being
  created by $inc, which is what would otherwise happen. Which of contract or
  limit was missing is worked out afterwards, only to phrase the error, and only
  once we know something was.
• The revert snapshot is derived, not read. _revertExpectedConsumption
  needs the value from before this call. Taking it from the result minus the
  amount applied means this caller takes back its own contribution even if other
  calls landed in between; reading it beforehand would reintroduce exactly the
  race being removed.

The service no longer reads the contract at all on this path, so the cached copy
can no longer be the basis of a write — it is only refreshed from the
authoritative result.

Verification

11 tests in src/test/contract.expected-consumption.test.ts, against a
stubbed repository and cache so the reads and writes themselves can be asserted.
The stub models the database honestly: incrementUsageLevels adds to whatever is
stored when it runs, which is the guarantee $inc gives and the one an
application-side read-modify-write cannot.

✓ src/test/contract.expected-consumption.test.ts (11 tests)
  ✓ records every limit, not just the last one written
  ✓ loses nothing when two requests arrive together
  ✓ loses nothing across many concurrent requests
  ✓ composes concurrent requests that touch different limits
  ✓ touches the contract once however many limits there are
  ✓ still applies a single limit
  ✓ does nothing at all when given nothing
  ✓ refuses the whole request when one limit does not exist
  ✓ says so when there is no contract at all
  ✓ keeps the previous value of every limit for reverting
  ✓ records this caller's own starting point, not whatever it read

Putting the batched read-modify-write back in place of the $inc call fails
four of them — the three concurrency tests and the round-trip count — so the
change is load-bearing rather than incidental:

× loses nothing when two requests arrive together
× loses nothing across many concurrent requests
× composes concurrent requests that touch different limits
× touches the contract once however many limits there are

Against a real MongoDB 7.0.16, exercising the $inc through the API rather than
a stub:

✓ src/test/contract.test.ts          (77 tests)
✓ src/test/feature-evaluation.test.ts (26 tests)
✓ src/test/service.test.ts           (44 tests)

Full suite: 13 files, 0 failures. npx tsc --noEmit is clean.